3D Graphics Programming with QuickDraw 3D 1.5.4

Managing Pick Objects

QuickDraw 3D provides a number of general routines for managing pick objects of any kind.

Q3Pick_GetType

You can use the Q3Pick_GetType function to get the type of a pick object.



 
TQ3ObjectType Q3Pick_GetType (TQ3PickObject pick);

pick: A pick object.

DESCRIPTION

The Q3Pick_GetType function returns, as its function result, the type of the pick object specified by the pick parameter. The types of pick objects currently supported by QuickDraw 3D are defined by these constants:



 
kQ3PickTypeWindowPoint

kQ3PickTypeWindowRect

If the specified pick object is invalid or is not one of these types, Q3Pick_GetType returns the value kQ3ObjectTypeInvalid .

Q3Pick_GetData

You can use the Q3Pick_GetData function to get the basic data associated with a pick object.



 
TQ3Status Q3Pick_GetData (

                     TQ3PickObject pick, 

                     TQ3PickData *data);

pick: A pick object.
data: On entry, a pointer to a pick data structure.

DESCRIPTION

The Q3Pick_GetData function returns, through the data parameter, basic information about the pick object specified by the pick parameter. See "Pick Data Structure" for a description of a pick data structure. Your application is responsible for allocating memory for the pick data structure before calling Q3Pick_GetData and for disposing of that memory when you're finished using that structure.

Q3Pick_SetData

You can use the Q3Pick_SetData function to set the basic data associated with a pick object.



 
TQ3Status Q3Pick_SetData (

                     TQ3PickObject pick, 

                     const TQ3PickData *data);

pick: A pick object.
data: A pointer to a pick data structure.

DESCRIPTION

The Q3Pick_SetData function sets the data associated with the pick object specified by the pick parameter to the data specified by the data parameter.

Q3Pick_GetVertexTolerance

You can use the Q3Pick_GetVertexTolerance function to get the current vertex tolerance of a pick object.



 
TQ3Status Q3Pick_GetVertexTolerance (

                     TQ3PickObject pick, 

                     float *vertexTolerance);

pick: A pick object.
vertexTolerance: On exit, the current vertex tolerance of the specified pick object.

DESCRIPTION

The Q3Pick_GetVertexTolerance function returns, in the vertexTolerance parameter, the current vertex tolerance of the pick object specified by the pick parameter. If the specified pick object does not support a vertex tolerance, Q3Pick_GetVertexTolerance generates an error. Tolerances are discussed in "Hit Identification" .

Q3Pick_SetVertexTolerance

You can use the Q3Pick_SetVertexTolerance function to set the vertex tolerance of a pick object.



 
TQ3Status Q3Pick_SetVertexTolerance (

                     TQ3PickObject pick, 

                     float vertexTolerance);

pick: A pick object.
vertexTolerance: The desired vertex tolerance of the specified pick object.

DESCRIPTION

The Q3Pick_SetVertexTolerance function sets the vertex tolerance of the pick object specified by the pick parameter to the tolerance specified by the vertexTolerance parameter. If the specified pick object does not support a vertex tolerance, Q3Pick_SetVertexTolerance generates an error. Tolerances are discussed in "Hit Identification" .

Q3Pick_GetEdgeTolerance

You can use the Q3Pick_GetEdgeTolerance function to get the current edge tolerance of a pick object.



 
TQ3Status Q3Pick_GetEdgeTolerance (

                     TQ3PickObject pick, 

                     float *edgeTolerance);

pick: A pick object.
edgeTolerance: On exit, the current edge tolerance of the specified pick object.

DESCRIPTION

The Q3Pick_GetEdgeTolerance function returns, in the edgeTolerance parameter, the current edge tolerance of the pick object specified by the pick parameter. If the specified pick object does not support an edge tolerance, Q3Pick_GetEdgeTolerance generates an error. Tolerances are discussed in "Hit Identification" .

Q3Pick_SetEdgeTolerance

You can use the Q3Pick_SetEdgeTolerance function to set the edge tolerance of a pick object.



 
TQ3Status Q3Pick_SetEdgeTolerance (

                     TQ3PickObject pick, 

                     float edgeTolerance);

pick: A pick object.
edgeTolerance: The desired edge tolerance of the specified pick object.

DESCRIPTION

The Q3Pick_SetEdgeTolerance function sets the edge tolerance of the pick object specified by the pick parameter to the tolerance specified by the edgeTolerance parameter. If the specified pick object does not support an edge tolerance, Q3Pick_SetEdgeTolerance generates an error. Tolerances are discussed in "Hit Identification" .

Q3Pick_GetPickDetailValidMask

You can use the Q3Pick_GetPickDetailValidMask function to return a mask designating the available TQ3PickDetail information. It should be followed with a call to Q3Pick_GetPickDetailData for each pickDetail bit set in the returned mask.



 
TQ3Status Q3Pick_GetPickDetailValidMask (

                     TQ3PickObject pick,

                     unsigned long index,

                     TQ3PickDetail *pickDetailValidMask);

pick: A pick object.
index: An index into a hit list.
pickDetailValidMask: The detail mask. For mask values, see "Hit Information" .

DESCRIPTION

Q3Pick_GetPickDetailValidMask returns, in the pickDetailValidMask parameter, a mask designating available pick detail data for the pick object pick and hit index index. If a bit in pickDetailValidMask is 0, it means that either the pick detail type wasn't specified when the pick was created, or if it was specified then it was meaningless for the type of pick object or the geometry intersected.

The index parameter is a zero-based value within the maximum number of hits obtained by callingQ3Pick_GetNumHits .

Q3Pick_GetPickDetailData

You can use the Q3Pick_GetPickDetailData function to obtain pick detail data for a given bit out of the mask returned by Q3Pick_GetPickDetailValidMask.



 
TQ3Status Q3Pick_GetPickDetailData (

                     TQ3PickObject pick,

                     unsigned long index,

                     TQ3PickDetail pickDetailValue,

                     void *detailData);

pick: A pick object.
index: An index into a hit list.
pickDetailValue: A single-bit mask.
detailData: The returned detail pick data.

DESCRIPTION

The Q3Pick_GetPickDetailData function returns, in the detailData parameter, the data corresponding to a pickDetailValue mask for the pick object pick and hit index index. See "Hit Detail Data" for descriptions of the information retrurned.

The value of pickDetailValue can be only one bit from the set of possible TQ3PickDetailMasks values returned by Q3Pick_GetPickDetailValidMask . TQ3PickDetailMasks values may not be combined using OR .

Upon successful completion, Q3Pick_GetPickDetailData returns a function result of kQ3Success .

Q3HitPath_EmptyData

You must use the Q3HitPath_EmptyData function to dispose of the path data that QuickDraw 3D allocated internally as the result of a previous call to Q3Pick_GetPickDetailData .



 
TQ3Status Q3HitPath_EmptyData (TQ3HitPath *hitPath);

hitPath: A hit path.

DESCRIPTION

The Q3HitPath_EmptyData function disposes of path data allocated internally as the result of a previous call to Q3Pick_GetPickDetailData . It returns kQ3Success if it completes successfully.

It is the responsibility of the application to dispose of the path data using Q3HitPath_EmptyData and the object and shapePart references using Q3Object_Dispose ; otherwise undisposed memory or objects will be leaked.

Q3Pick_GetNumHits

You can use the Q3Pick_GetNumHits function to get the number of hits in the hit list of a pick object.



 
TQ3Status Q3Pick_GetNumHits (

                     TQ3PickObject pick, 

                     unsigned long *numHits);

pick: A pick object.
numHits: On exit, the number of items in the hit list of the specified pick object.

DESCRIPTION

The Q3Pick_GetNumHits function returns, in the numHits parameter, the number of items in the hit list associated with the pick object specified by the pick parameter. This number never exceeds the maximum number of items specified in the pick object's data structure.

Q3Pick_EmptyHitList

You can use the Q3Pick_EmptyHitList function to empty a pick object's hit list.



 
TQ3Status Q3Pick_EmptyHitList (TQ3PickObject pick);

pick: A pick object.

DESCRIPTION

The Q3Pick_EmptyHitList function disposes of all QuickDraw 3D-allocated memory occupied by the hit list associated with the pick object specified by the pick parameter. (This memory is also disposed of when the specified pick object is disposed of.) Q3Pick_EmptyHitList also sets the hit count of the specified pick object to 0.